Serialisasi TypeScript: Pola Keamanan Tipe JSON

Dalam lanskap pengembangan web yang terus berkembang, memastikan integritas data dan mencegah kesalahan runtime adalah hal yang terpenting. TypeScript, dengan sistem tipenya yang kuat, menyediakan mekanisme yang ampuh untuk mencapai tujuan ini, terutama ketika berurusan dengan serialisasi dan deserialisasi JSON. Panduan komprehensif ini mengeksplorasi berbagai pola dan teknik untuk mengimplementasikan penanganan JSON yang aman untuk tipe di proyek TypeScript Anda, memungkinkan Anda untuk membangun aplikasi yang lebih andal dan mudah dipelihara untuk audiens global.

Memahami Masalah: JSON dan Sistem Tipe TypeScript

JSON (JavaScript Object Notation) adalah standar de facto untuk pertukaran data di web. Namun, sifat JSON yang tidak bertipe secara inheren menimbulkan tantangan ketika diintegrasikan dengan bahasa bertipe statis seperti TypeScript. Tanpa penegakan tipe yang tepat, pengembang berisiko mengalami kesalahan runtime karena ketidakcocokan tipe, format data yang tidak terduga, atau bidang yang hilang. Hal ini dapat menyebabkan aplikasi macet, kerentanan keamanan, dan pengguna yang frustrasi di seluruh dunia.

Pertimbangkan skenario di mana Anda mengambil data dari API publik. Dokumentasi API menyatakan bahwa endpoint tertentu mengembalikan array objek pengguna, yang masing-masing berisi properti `id`, `name`, dan `email`. Tanpa keamanan tipe, Anda mungkin berasumsi struktur data dan mulai menggunakannya dalam aplikasi Anda. Namun, apa yang terjadi jika API mengubah format responsnya, memperkenalkan bidang baru, atau mengubah tipe data bidang yang ada? Aplikasi Anda dapat rusak, menyebabkan pengalaman pengguna yang buruk.

TypeScript mengatasi masalah ini dengan memungkinkan Anda mendefinisikan antarmuka atau tipe yang mewakili struktur data JSON Anda. Ini memungkinkan kompilator TypeScript untuk memeriksa kesalahan tipe pada waktu kompilasi, mencegah banyak potensi masalah runtime. Dengan memberlakukan keamanan tipe selama serialisasi dan deserialisasi, Anda dapat secara signifikan meningkatkan ketahanan dan kemudahan pemeliharaan basis kode Anda.

Konsep dan Teknik Inti

1. Mendefinisikan Antarmuka dan Tipe TypeScript

Dasar dari penanganan JSON yang aman untuk tipe adalah mendefinisikan antarmuka atau tipe TypeScript yang secara akurat memodelkan struktur data JSON Anda. Sebuah antarmuka mendefinisikan kontrak untuk bentuk sebuah objek, menentukan tipe data propertinya. Alias tipe menyediakan cara yang lebih ringkas untuk membuat tipe khusus.

Contoh:

            interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: { //Properti opsional
      street: string;
      city: string;
      country: string;
  }
}

//Atau menggunakan tipe
type UserType = {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
      street: string;
      city: string;
      country: string;
  }
}

            

              
                Copy
              
            
          

Dalam contoh ini, antarmuka `User` mendefinisikan struktur yang diharapkan dari objek pengguna. Properti `address` bersifat opsional, dilambangkan dengan simbol `?`, yang merupakan pola umum untuk menangani data yang berpotensi hilang. Menggunakan antarmuka dan alias tipe menyediakan pemeriksaan tipe waktu kompilasi, mengurangi risiko kesalahan runtime saat bekerja dengan data JSON.

2. Serialisasi: Mengonversi Objek TypeScript ke JSON

Serialisasi adalah proses mengonversi objek TypeScript menjadi string JSON. Ini biasanya dilakukan saat mengirim data ke server atau menyimpannya dalam database. Sistem tipe TypeScript memberikan jaminan waktu kompilasi bahwa objek tersebut mematuhi tipe yang ditentukan, mencegah kesalahan yang tidak terduga. Metode `JSON.stringify()` bawaan digunakan untuk serialisasi. Namun, penting untuk mempertimbangkan kasus ekstrem seperti tipe objek khusus atau objek tanggal selama serialisasi.

Contoh:

            const user: User = {
  id: 123,
  name: 'John Doe',
  email: 'john.doe@example.com',
  isActive: true,
  address: {
      street: '123 Main St',
      city: 'Anytown',
      country: 'USA'
  }
};

const userJSON: string = JSON.stringify(user, null, 2); // JSON yang dicetak dengan indah dengan 2 spasi untuk indentasi
console.log(userJSON);

            

              
                Copy
              
            
          

Cuplikan kode ini menunjukkan cara melakukan serialisasi objek `User` menjadi string JSON menggunakan `JSON.stringify()`. Argumen kedua, `null`, adalah fungsi pengganti yang memungkinkan Anda menyesuaikan proses serialisasi. Argumen ketiga, `2`, menentukan jumlah spasi yang akan digunakan untuk indentasi, membuat keluaran JSON lebih mudah dibaca. Dalam aplikasi dunia nyata, pertimbangkan untuk menangani kesalahan yang mungkin timbul selama `JSON.stringify()` dan menyesuaikannya untuk menangani objek Tanggal dan tipe khusus lainnya.

3. Deserialisasi: Mengonversi String JSON ke Objek TypeScript

Deserialisasi adalah proses mengonversi string JSON kembali menjadi objek TypeScript. Ini biasanya dilakukan saat menerima data dari server atau membacanya dari file. Di sinilah keamanan tipe sangat penting. Secara langsung mengubah hasil `JSON.parse()` ke antarmuka yang Anda tentukan tidak akan secara otomatis melakukan validasi tipe. Ini hanya memberi tahu kompilator untuk 'mempercayai' bahwa data tersebut bertipe yang ditentukan. Setiap perbedaan antara data dan antarmuka akan menghasilkan kesalahan runtime.

Untuk mendeserialisasi JSON dengan aman, ada beberapa pendekatan, masing-masing dengan keuntungan dan kerugiannya. Ini melibatkan validasi data yang cermat untuk memastikan bahwa data JSON yang masuk sesuai dengan struktur dan tipe data yang diharapkan.

3.1 Casting Langsung (dengan hati-hati)

Pendekatan ini melibatkan penggunaan pernyataan tipe untuk mengubah hasil `JSON.parse()` ke antarmuka Anda. Ini adalah cara paling sederhana tetapi juga paling berisiko untuk mendeserialisasi data JSON karena tidak melakukan validasi runtime. Ini hanya memberi tahu kompilator bahwa data cocok dengan tipe tersebut. Metode ini berfungsi ketika Anda *mempercayai* sumber JSON, seperti dari API internal Anda atau kode yang Anda kendalikan.

Contoh:

            const userJSON: string = '{
  "id": 123,
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "isActive": true
}';

const user: User = JSON.parse(userJSON) as User;
console.log(user.name);

            

              
                Copy
              
            
          

Dalam contoh ini, hasil dari `JSON.parse(userJSON)` diubah ke antarmuka `User`. Meskipun ini dikompilasi tanpa kesalahan, jika string `userJSON` tidak sesuai dengan antarmuka `User` (misalnya, kehilangan properti atau tipe data yang salah), Anda akan mengalami kesalahan runtime saat mengakses properti.

3.2 Validasi dengan Pustaka (Disarankan)

Menggunakan pustaka validasi khusus adalah pendekatan yang disarankan untuk deserialisasi yang aman untuk tipe. Pustaka seperti `zod`, `io-ts`, dan `class-validator` menyediakan fitur-fitur kuat untuk memvalidasi data JSON terhadap skema yang ditentukan. Pustaka-pustaka ini memungkinkan Anda untuk menggambarkan struktur dan tipe data yang diharapkan dan secara otomatis memvalidasi data pada waktu runtime, memberikan pesan kesalahan terperinci jika validasi gagal.

Menggunakan Zod: Zod adalah pustaka populer untuk validasi skema dengan API yang sederhana dan intuitif. Sangat mudah untuk mendefinisikan skema dan memvalidasi data terhadapnya. Pertama, instal Zod:

            npm install zod
            

              
                Copy
              
            
          

Kemudian, gunakan Zod untuk mendefinisikan skema yang cocok dengan antarmuka Anda. Mari kita asumsikan kita memiliki antarmuka `User` yang didefinisikan di atas.

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(), // Validasi email
  isActive: z.boolean(),
  address: z.optional(z.object({
    street: z.string(),
    city: z.string(),
    country: z.string()
  }))
});

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
    street: string;
    city: string;
    country: string;
  }
}

            

              
                Copy
              
            
          

Sekarang, kita dapat mengurai dan memvalidasi string JSON:

            const userJSON: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true
}';

try {
    const parsedUser: User = UserSchema.parse(JSON.parse(userJSON));
    console.log(parsedUser.name);
} catch (error: any) {
    console.error('Kesalahan validasi:', error.errors);
}

            

              
                Copy
              
            
          

Dalam contoh ini, `UserSchema.parse(JSON.parse(userJSON))` mencoba mengurai dan memvalidasi string `userJSON`. Jika data tidak sesuai dengan skema, `ZodError` akan dilemparkan, memungkinkan Anda untuk menangani kesalahan validasi dengan baik. Blok `try...catch` menangani setiap kesalahan validasi yang mungkin terjadi. Ini adalah metode yang lebih aman dan lebih andal untuk mendeserialisasi data JSON.

Menggunakan io-ts: io-ts adalah pustaka yang menggabungkan pemeriksaan tipe runtime dengan konsep pemrograman fungsional. Ini memungkinkan Anda untuk mendefinisikan codec yang menyandi dan mendekode data dan memvalidasi data JSON terhadap codec ini. Lebih rumit untuk memulai tetapi menyediakan fitur yang lebih kuat untuk skenario validasi yang kompleks.

            npm install io-ts

            

              
                Copy
              
            
          

            import * as t from 'io-ts';
import { isRight } from 'fp-ts/lib/Either';

const UserCodec = t.type({
  id: t.number,
  name: t.string,
  email: t.string,
  isActive: t.boolean,
  address: t.union([ //menggunakan union untuk mewakili address atau undefined
    t.undefined,
    t.type({
        street: t.string,
        city: t.string,
        country: t.string
    })
  ])
});

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
    street: string;
    city: string;
    country: string;
  }
}


const userJSON: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true
}';

const decoded = UserCodec.decode(JSON.parse(userJSON));

if (isRight(decoded)) {
  const user: User = decoded.right;
  console.log(user.name);
} else {
  console.error('Kesalahan validasi:', decoded.left);
}

            

              
                Copy
              
            
          

Dalam contoh ini, `UserCodec.decode(JSON.parse(userJSON))` mencoba mendekode dan memvalidasi string `userJSON`. `isRight()` dari pustaka `fp-ts` memeriksa hasil validasi, dan kesalahan validasi diberikan jika JSON yang didekode tidak sesuai dengan `UserCodec`.

Pustaka seperti `zod` dan `io-ts` menawarkan keuntungan dalam deserialisasi JSON yang aman untuk tipe dengan menyediakan:

• Validasi Runtime: Mereka memvalidasi data terhadap skema pada waktu runtime, mengidentifikasi kesalahan sebelum menyebabkan masalah.
• Pesan Kesalahan yang Jelas: Mereka memberikan pesan kesalahan yang spesifik dan membantu untuk menunjukkan masalah validasi data.
• Inferensi Tipe: Mereka sering bekerja dengan baik dengan inferensi tipe TypeScript, membuat definisi tipe lebih mudah dipelihara.

3.3 Fungsi Deserialisasi Kustom

Pendekatan lain adalah menulis fungsi deserialisasi kustom yang menangani konversi data JSON ke antarmuka TypeScript Anda. Ini memungkinkan Anda untuk menangani tipe data atau transformasi tertentu yang tidak mudah dicapai dengan pustaka validasi yang lebih sederhana. Pendekatan ini memberikan kontrol yang lebih besar tetapi membutuhkan lebih banyak upaya.

Contoh:

            interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  createdAt: Date;
}

function deserializeUser(json: string): User | null {
  try {
    const parsed = JSON.parse(json);

    if (
      typeof parsed.id !== 'number' ||
      typeof parsed.name !== 'string' ||
      typeof parsed.email !== 'string' ||
      typeof parsed.isActive !== 'boolean' ||
      typeof parsed.createdAt !== 'string'
    ) {
      return null; // Data tidak valid
    }

    // Asumsi createdAt adalah string dalam format ISO
    const createdAtDate = new Date(parsed.createdAt);
    if (isNaN(createdAtDate.getTime())) {
      return null; //Tanggal tidak valid
    }

    return {
      id: parsed.id,
      name: parsed.name,
      email: parsed.email,
      isActive: parsed.isActive,
      createdAt: createdAtDate,
    };
  } catch (error) {
    console.error('Kesalahan deserialisasi:', error);
    return null;
  }
}

const userJSON: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true,
  "createdAt": "2024-01-26T10:00:00.000Z"
}';

const user: User | null = deserializeUser(userJSON);

if (user) {
  console.log(user.name);
  console.log(user.createdAt);
} else {
  console.log('Data pengguna tidak valid');
}

            

              
                Copy
              
            
          

Dalam contoh ini, fungsi `deserializeUser` mengurai string JSON dan memvalidasi tipe data properti. Ini juga menangani konversi properti `createdAt` dari string ke objek `Date`. Jika data tidak valid, fungsi mengembalikan `null`. Fungsi kustom ini memberikan kontrol penuh atas proses deserialisasi, memungkinkan Anda untuk menangani transformasi data yang kompleks.

4. Menangani Properti Opsional dan Nilai Null

Data JSON sering kali menyertakan properti opsional dan nilai null. Sistem tipe TypeScript menyediakan mekanisme untuk menangani kasus-kasus ini dengan baik. Properti opsional dilambangkan dengan akhiran `?` dalam definisi antarmuka. Nilai `null` memerlukan pertimbangan yang cermat selama deserialisasi. Saat menggunakan pustaka validasi seperti Zod, Anda dapat mendefinisikan bidang opsional dengan `z.optional()` atau `z.nullable()` untuk mengizinkan `null` dan undefined, tergantung pada struktur JSON yang dikembalikan API.

Contoh:

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  isActive: z.boolean(),
  address: z.optional(z.object({
    street: z.string(),
    city: z.string(),
    country: z.string()
  })),
  profilePicture: z.nullable(z.string()) // Mengizinkan nilai null
});

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
  address?: {
    street: string;
    city: string;
    country: string;
  };
  profilePicture: string | null; // Antarmuka Typescript mencerminkan nullable
}

const userJSONWithAddress: string = '{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "isActive": true,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "country": "USA"
  },
  "profilePicture": "/path/to/image.jpg"
}';

const userJSONWithoutAddress: string = '{
  "id": 456,
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "isActive": false,
  "profilePicture": null
}';

try {
    const userWithAddress: User = UserSchema.parse(JSON.parse(userJSONWithAddress));
    console.log(userWithAddress);

    const userWithoutAddress: User = UserSchema.parse(JSON.parse(userJSONWithoutAddress));
    console.log(userWithoutAddress);
} catch (error) {
    console.error("Kesalahan validasi", error);
}

            

              
                Copy
              
            
          

Dalam contoh ini, properti `address` bersifat opsional. `profilePicture` dapat memiliki data string atau `null`. Zod, atau alat validasi serupa, menangani validasi data.

5. Generik untuk Serialisasi dan Deserialisasi yang Dapat Digunakan Kembali

Generik dapat digunakan untuk membuat fungsi serialisasi dan deserialisasi yang dapat digunakan kembali yang berfungsi dengan berbagai tipe. Ini mengurangi duplikasi kode dan mempromosikan penggunaan kembali kode. Menggunakan generik memungkinkan Anda untuk menulis fungsi yang dapat berfungsi dengan tipe yang berbeda tanpa perlu menulis fungsi terpisah untuk setiap tipe.

Contoh:

            import { z, ZodSchema } from 'zod';

function safeParse(schema: ZodSchema, json: string): T | null {
  try {
    const parsed = JSON.parse(json);
    return schema.parse(parsed);
  } catch (error) {
    console.error('Kesalahan parsing:', error);
    return null;
  }
}

interface Product {
  id: number;
  name: string;
  price: number;
}

const ProductSchema: ZodSchema = z.object({
  id: z.number(),
  name: z.string(),
  price: z.number()
});

const productJSON: string = '{
  "id": 1,
  "name": "Example Product",
  "price": 99.99
}';

const product: Product | null = safeParse(ProductSchema, productJSON);

if (product) {
  console.log(product.name);
} else {
  console.log('Data produk tidak valid');
}

            

              
                Copy
              
            
          

Fungsi `safeParse` adalah fungsi generik yang mengambil skema Zod dan string JSON. Ini mengurai string JSON dan memvalidasinya terhadap skema yang disediakan. Jika penguraian atau validasi gagal, itu mengembalikan `null`. Fungsi generik ini dapat digunakan kembali untuk tipe yang berbeda hanya dengan meneruskan skema Zod yang sesuai.

Praktik Terbaik dan Pertimbangan Tingkat Lanjut

1. Praktik Terbaik Validasi Data

• Definisi Skema Terpusat: Definisikan skema Anda di lokasi pusat untuk memastikan konsistensi dan kemudahan pemeliharaan.
• Validasi Komprehensif: Validasi semua properti dan tipe data.
• Penanganan Kesalahan: Terapkan penanganan kesalahan yang kuat untuk menangkap dan melaporkan kesalahan validasi.
• Versioning Skema: Pertimbangkan versioning skema ketika API atau struktur data Anda berkembang. Ini memungkinkan Anda untuk mendukung beberapa versi format data Anda, meminimalkan perubahan yang merusak.
• Pengujian: Tulis pengujian unit untuk logika serialisasi dan deserialisasi Anda untuk memastikan kebenaran dan keandalannya. Sertakan pengujian untuk skenario data yang valid dan tidak valid.

2. Menangani Struktur Data Kompleks

Untuk struktur data yang kompleks, Anda mungkin perlu menyarangkan skema atau menggunakan skema rekursif di pustaka validasi Anda. Struktur kompleks dapat direpresentasikan menggunakan antarmuka yang disarangkan atau dengan menyusun skema yang ada menggunakan pustaka seperti Zod atau io-ts.

Contoh Skema Rekursif dengan Zod:

            import { z } from 'zod';

interface TreeNode {
  value: string;
  children: TreeNode[];
}

const TreeNodeSchema: z.ZodSchema = z.object({
  value: z.string(),
  children: z.lazy(() => z.array(TreeNodeSchema)), // Definisi rekursif
});

const treeJSON: string = '{
  "value": "Root",
  "children": [
    {
      "value": "Child 1",
      "children": []
    },
    {
      "value": "Child 2",
      "children": [
        {
          "value": "Grandchild 1",
          "children": []
        }
      ]
    }
  ]
}';

try {
  const parsedTree: TreeNode = TreeNodeSchema.parse(JSON.parse(treeJSON));
  console.log(parsedTree);
} catch (error) {
  console.error("Kesalahan validasi", error);
}

            

              
                Copy
              
            
          

Contoh ini menunjukkan cara mendefinisikan skema rekursif untuk struktur data seperti pohon menggunakan Zod.

3. Pertimbangan Kinerja

• Pilih Pustaka yang Tepat: Pilih pustaka validasi yang memenuhi persyaratan kinerja Anda. Pustaka seperti `zod` dan `io-ts` umumnya berkinerja baik, tetapi kinerja pustaka tertentu dapat bervariasi.
• Optimalkan Skema: Rancang skema secara efisien. Hindari langkah-langkah validasi yang tidak perlu.
• Caching: Cache data yang diserialisasi bila memungkinkan untuk menghindari overhead serialisasi yang berulang. Namun, selalu prioritaskan kebenaran data daripada kinerja untuk aplikasi penting.

4. Pertimbangan Keamanan

• Sanitasi Input: Sanitasi data yang disediakan pengguna sebelum serialisasi untuk mencegah kerentanan injeksi. Ini adalah aspek penting dari pengkodean yang aman, memastikan bahwa kode berbahaya tidak diserialisasi atau dideserialisasi.
• Validasi Data: Validasi data secara menyeluruh untuk mencegah kerentanan. Validasi yang kuat membantu melindungi dari serangan di mana pelaku jahat mencoba memberikan data yang tidak valid untuk memicu kesalahan atau pelanggaran keamanan.
• Hindari `eval()` dan `new Function()`: Jangan pernah menggunakan `eval()` atau `new Function()` dengan data JSON yang tidak tepercaya. Metode-metode ini dapat menciptakan risiko keamanan yang parah dengan mengizinkan eksekusi kode arbitrer.

5. Internasionalisasi dan Lokalisasi

Saat mengembangkan aplikasi global, pertimbangkan dampak serialisasi dan deserialisasi pada internasionalisasi (i18n) dan lokalisasi (l10n). Wilayah yang berbeda menggunakan format tanggal/waktu, simbol mata uang, dan konvensi pemformatan angka yang berbeda. Logika serialisasi dan deserialisasi Anda harus dapat menangani variasi ini. Pustaka seperti Moment.js atau date-fns sering digunakan untuk menangani pemformatan tanggal dan waktu. Pertimbangkan untuk menggunakan objek `Intl` di JavaScript untuk pemformatan angka dan mata uang untuk mendukung lokal yang berbeda.

Kesimpulan: Membangun Aplikasi Andal Secara Global

Sistem tipe TypeScript, dikombinasikan dengan pustaka validasi yang kuat, memberdayakan pengembang untuk membangun aplikasi yang lebih andal dan mudah dipelihara dengan menyediakan penanganan JSON yang aman untuk tipe secara komprehensif. Dengan mengadopsi pola dan teknik yang dijelaskan dalam panduan ini, Anda dapat mengurangi kesalahan runtime, meningkatkan integritas data, dan memastikan stabilitas aplikasi web Anda untuk pengguna di seluruh dunia. Merangkul keamanan tipe tidak hanya menguntungkan tim pengembangan Anda dengan meningkatkan kualitas kode tetapi juga meningkatkan pengalaman pengguna dengan mencegah kesalahan yang tidak terduga dan memastikan representasi data yang konsisten, berkontribusi pada aplikasi yang lebih kuat dan dapat diandalkan secara global.

Menerapkan pola-pola ini, mulai dari mendefinisikan antarmuka dan menggunakan pustaka validasi seperti Zod dan io-ts hingga menangani properti opsional dan nilai null, akan menghasilkan kode yang lebih kuat dan mudah dipelihara. Ingatlah untuk memprioritaskan validasi komprehensif, penanganan kesalahan, dan praktik terbaik keamanan. Dengan mengadopsi praktik-praktik ini, pengembang dapat membangun aplikasi yang lebih tahan terhadap kesalahan, lebih mudah dipelihara, dan memberikan pengalaman pengguna yang lebih baik di semua wilayah dan budaya.